ATSUGetFontFeatureSelectors

OSStatus ATSUGetFontFeatureSelectors (
                     ATSUFontID iFont,
                     ATSUFontFeatureType iType,
                     ItemCount iMaximumSelectors,
                     ATSUFontFeatureSelector oSelectors[],
                     Boolean oSelectorIsOnByDefault[],
                     ItemCount *oActualSelectorCount,
                     Boolean *oIsMutuallyExclusive);

iFont

A value of type ATSUFontID. Pass the ID of the font for whose feature type you want to count the number of feature selectors.

iType

A value of type ATSUFontFeatureType. Pass a valid feature type whose font selectors you want to determine.

iMaximumSelectors

The maximum number of feature selectors in the font. Typically, this is equivalent to the number of elements in the oSelectors array. To determine this value, see the discussion below.

oSelectors

An array of values of type ATSUFontFeatureSelector or one of the feature selector constants described in Apple Advanced Typography Constants. Before calling ATSUGetFontFeatureSelectors, pass a pointer to memory that you have allocated for this array. If you are uncertain of how much memory to allocate, see the discussion below. On return, the array contains a list of all the feature selectors available for a given feature type. You cannot pass NULL for this parameter.

oSelectorIsOnByDefault

An array of Boolean values. Before calling ATSUGetFontFeatureSelectors, pass a pointer to memory that you have allocated for this array. If you are uncertain of how much memory to allocate, see the discussion below. On return, each element in the array indicates whether the corresponding feature selector is on. If true, the feature selector is on by default. You cannot pass NULL for this parameter.

oActualSelectorCount

A pointer to a count. On return, the actual number of feature selectors defined for a given feature type in a font. This may be greater than the value passed in the iMaximumSelectors parameter. You cannot pass NULL for this parameter.

oIsMutuallyExclusive

A pointer to Boolean value. On return, the value indicates whether more than one font feature selector can be on at once. If true, only one selector can be used at a time. You cannot pass NULL for this parameter.

function result

A result code. The result code kATSUInvalidFontErr indicates that the ID does not correspond to any installed font. For a list of other ATSUI-specific result codes, see Result Codes.

DISCUSSION

The ATSUGetFontFeatureSelectors function obtains a list of the feature selectors that are defined for a given feature type in a font. You can use this information to set the font features and selectors in a style object.

The best way to use ATSUGetFontFeatureSelectors is to call it twice:

Pass the ID of the font whose feature selectors you want to determine in the iFont parameter, NULL for the oSelectors parameter, and 0 for the other parameters. ATSUGetFontFeatureSelectors returns the size of the feature type array in the oActualSelectorCount parameter.
Allocate enough space for an array of the returned size, then call the function again, passing a pointer in the oSelectors parameter; on return, the pointer references the array of feature selectors for the given feature type.
You can also determine how much memory to allocate for the oSelectors array by calling the function ATSUCountFontFeatureSelectors, which will return the total number of font feature selectors in a particular feature type.

VERSION NOTES

Available beginning with ATSUI 1.0.